<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Panel</title>
    <link rel="stylesheet" href="http://yui.yahooapis.com/3.4.0pr3/build/cssgrids/grids-min.css">
    <link rel="stylesheet" href="../assets/css/main.css">
    <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
    <script src="../../build/yui/yui-min.js"></script>
</head>
<body>

<div id="doc">
    <h1>Panel</h1>

    
        <a href="#toc" class="jump">Jump to Table of Contents</a>
    

    <div class="yui3-g">
        <div id="main" class="yui3-u">
            <div class="content"><div class="intro">
    <p>
    Panel is a Widget that mimics the functionality of a regular OS window. It is similar to Overlay, with added functionality to support modality, event listeners on which to auto-hide and auto-focus, header/footer button support and skins. Panel does not have any implementation code of it's own. It implements a set of extensions that provide certain sets of functionality. The <a href="../widget/widget-build.html">"Creating Custom Widget Classes"</a> example shows how you can use these extensions to build classes which mix and match some of the above features.
    </p>
</div>

<h2 id="getting-started">Getting Started</h2>

<p>
To include the source files for Panel and its dependencies, first load
the YUI seed file if you haven't already loaded it.
</p>

<pre class="code prettyprint">&lt;script src=&quot;http:&#x2F;&#x2F;yui.yahooapis.com&#x2F;3.4.1&#x2F;build&#x2F;yui&#x2F;yui-min.js&quot;&gt;&lt;&#x2F;script&gt;</pre>


<p>
Next, create a new YUI instance for your application and populate it with the
modules you need by specifying them as arguments to the <code>YUI().use()</code> method.
YUI will automatically load any dependencies required by the modules you
specify.
</p>

<pre class="code prettyprint">&#x2F;&#x2F; Create a new YUI instance and populate it with the required modules.
YUI().use(&#x27;panel&#x27;, function (Y) {
    &#x2F;&#x2F; Panel is available and ready for use. Add implementation
    &#x2F;&#x2F; code here.
});</pre>


<p>
For more information on creating YUI instances and on the
<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the
documentation for the <a href="../yui/index.html">YUI Global object</a>.
</p>


<h2 id="creating-a-panel">Creating a Panel</h2>

<p>
This simple example will create a Panel with default functionality. By default, a Panel is rendered with a "close" button added to the header, with modality disabled, and will be hidden if the <code>esc</code> key or "close" button is pressed.
</p>

<pre class="code prettyprint">YUI().use(&#x27;panel&#x27;, function(Y) {

    var panel = new Y.Panel({
        srcNode : &#x27;#myPanelContent&#x27;,
        width   : 400,
        centered: true,
        render  : true
    });

});</pre>


<h2 id="modal-panel">Modal Panel</h2>

<p>
A Panel is not modal by default. This functionality can be changed through the <code>modal</code> attribute, either during instantiation or later through the <code>set()</code> method.
</p>

<pre class="code prettyprint">YUI().use(&#x27;panel&#x27;, function(Y) {

    var panel = new Y.Panel({
        srcNode: &#x27;#myPanelContent&#x27;,
        width  : 400,
        modal  : true &#x2F;&#x2F; Make the Panel modal
    });

    panel.render();
    &#x2F;&#x2F; Optionally, we could have written:
    &#x2F;&#x2F; panel.set(&#x27;modal&#x27;, true);

});</pre>


<p>
Panels can be nested in one another, and have different modal behavior. For instance, a modal Panel may launch a non-modal Panel on top of it. The <a href="http://yuilibrary.com/yui/docs/api/classes/WidgetModality.html"><code>WidgetModality</code></a> extension takes care of nesting behavior so no extra code is required for the implementer. Refer to the examples for more information.
</p>

<h2 id="choosing-when-to-focus-and-hide">Choosing When to Focus and Hide</h2>

<p>
By default, a modal Panel will return focus to itself if anything else on the page receives focus or is clicked. On the other hand, clicking the "close" button, or pressing the <code>esc</code> key will hide it. Both of these options can be configured as needed through the <code>hideOn</code> and <code>focusOn</code> attributes.
</p>

<p>
The following code snippet shows how to change the default "hide" behavior. Instead of hiding when the <code>esc</code> key is pressed, the Panel hides whenever something outside its <code>boundingBox</code> is pressed, or when a certain element on the page (with an id of <code>anotherNode</code>) is clicked.
</p>

<pre class="code prettyprint">YUI().use(&#x27;panel&#x27;, function(Y) {

    var panel = new Y.Panel({
        srcNode : &#x27;#myPanelContent&#x27;,
        width   : 400,
        centered: true,
        modal   : false,
        render  : true,

        &#x2F;&#x2F; The &#x60;hideOn&#x60; Attribute takes an array of objects with a required
        &#x2F;&#x2F; &#x60;eventName&#x60; property, and two optional properties:
        &#x2F;&#x2F; &#x60;node&#x60; and &#x60;keyCode&#x60;.
        hideOn: [
            {
                &#x2F;&#x2F; When we don&#x27;t specify a &#x60;node&#x60;,
                &#x2F;&#x2F; it defaults to the &#x60;boundingBox&#x60; of this Panel instance.
                eventName: &#x27;clickoutside&#x27;
            },
            {
                &#x2F;&#x2F; Listen to click events on the &#x60;node&#x60; that was specified.
                node     : Y.one(&#x27;#anotherNode&#x27;),
                eventName: &#x27;click&#x27;
            }
        ]
    });

});</pre>


<p>
Similarly, the <code>focusOn</code> attribute can be changed to configure the default focus behavior.
</p>

<pre class="code prettyprint">var panel = new Y.Panel({
    srcNode : &#x27;#myPanelContent&#x27;,
    width   : 400,
    centered: true,
    modal   : false,
    render  : true,

    &#x2F;&#x2F; The &#x60;hideOn&#x60; Attribute takes an array of objects with a required
    &#x2F;&#x2F; &#x60;eventName&#x60; property, and two optional properties:
    &#x2F;&#x2F; &#x60;node&#x60; and &#x60;keyCode&#x60;.
    focusOn: [
        {
            &#x2F;&#x2F; When we don&#x27;t specify a &#x60;node&#x60;,
            &#x2F;&#x2F; it defaults to the &#x60;boundingBox&#x60; of this Panel instance.
            eventName: &#x27;clickoutside&#x27;
        },
        {
            &#x2F;&#x2F; Listen to click events on the &#x60;node&#x60; that was specified.
            node     : Y.one(&#x27;#anotherNode&#x27;),
            eventName: &#x27;click&#x27;
        }
    ]
});

});</pre>


<p>
To simply get rid of the default behavior, we could just set the <code>focusOn</code> and <code>hideOn</code> attributes to empty Arrays.
</p>

<h2 id="headerfooter-button-support">Header/Footer Button Support</h2>

<p>
Panel supports header/footer buttons through the <a href="http://yuilibrary.com/yui/docs/api/classes/WidgetButtons.html"><code>WidgetButtons</code></a> and <a href="http://yuilibrary.com/yui/docs/api/classes/WidgetStdMod.html"><code>WidgetStdMod</code></a> extensions. By default, it comes with a "close" button represented by the "x" in the top-right corner of the header. As a developer, you can easily add/remove buttons to the header or the footer, change the style of existing buttons, or change the markup that is used to render the buttons.
</p>

<pre class="code prettyprint">YUI().use(&#x27;panel&#x27;, function(Y) {

    function doSomethingElse () {
        &#x2F;&#x2F; ...
    }

    var panel = new Y.Panel({
        srcNode : &#x27;#myPanelContent&#x27;,
        width   : 400,
        centered: true,

        &#x2F;&#x2F; Make changes to the buttons through the &#x60;buttons&#x60; attribute,
        &#x2F;&#x2F; which takes an Array of Objects.
        buttons: [
            {
                &#x2F;&#x2F; Each object has a &#x60;value&#x60; property,
                &#x2F;&#x2F; which can be text or an HTML string.
                value: &quot;Okay&quot;,

                &#x2F;&#x2F; The &#x60;action&#x60; property takes the Function that should be
                &#x2F;&#x2F; executed on a click event.
                action: function (e) {
                    e.preventDefault();
                    panel.hide();
                    doSomethingElse();
                },

                &#x2F;&#x2F; The &#x60;section&#x60; property tells where to render the button and
                &#x2F;&#x2F; should be &#x60;Y.WidgetStdMod.HEADER&#x60; or &#x60;Y.WidgetStdMod.FOOTER&#x60;.
                section: Y.WidgetStdMod.FOOTER

                &#x2F;&#x2F; Optional &#x60;classNames&#x60; property to add CSS classes to the 
                &#x2F;&#x2F; button Node.

                &#x2F;&#x2F; optional &#x60;href&#x60; property if you are linking to an URL.
            }
        ]
    });

    panel.render();

});</pre>


<p>
If you want to append buttons to the ones that are already present within the Panel, you can use the <code>addButton()</code> method.
</p>

<pre class="code prettyprint">var cancelButton = {
    value : &#x27;Cancel&#x27;,
    action: function (e) {
        e.preventDefault();
        &#x2F;&#x2F; ...
    },

    &#x2F;&#x2F; &#x27;header&#x27;, &#x27;footer&#x27; or Y.WidgetStdMod.HEADER also work here.
    section: Y.WidgetStdMod.FOOTER
};

panel.addButton(cancelButton);</pre>


<h2 id="notes-regarding-older-browsers">Notes Regarding Older Browsers</h2>

<p>
Panel is tested across the A-grade browser set according to the <a href="http://yuilibrary.com/yui/docs/tutorials/gbs/" alt="Graded Browser Support">GBS Browser Test Baseline</a> as of July 2011.
</p>

<p>
However, developers implementing Panel and other components which rely on <code>z-index</code> support in IE6 and IE7 should be aware of the concept of <a href="https://developer.mozilla.org/en/Understanding_CSS_z-index/Stacking_context_example_2" alt="Stacking Context in IE">stacking context</a>. Essentially, when setting the <code>z-index</code> of the widget, you should ensure that the Widget's parent does not have a lower <code>z-index</code>.
</p>
</div>
        </div>

        <div id="sidebar" class="yui3-u">
            
                <div id="toc" class="sidebox">
                    <div class="hd">
                        <h2 class="no-toc">Table of Contents</h2>
                    </div>

                    <div class="bd">
                        <ul class="toc">
<li>
<a href="#getting-started">Getting Started</a>
</li>
<li>
<a href="#creating-a-panel">Creating a Panel</a>
</li>
<li>
<a href="#modal-panel">Modal Panel</a>
</li>
<li>
<a href="#choosing-when-to-focus-and-hide">Choosing When to Focus and Hide</a>
</li>
<li>
<a href="#headerfooter-button-support">Header/Footer Button Support</a>
</li>
<li>
<a href="#notes-regarding-older-browsers">Notes Regarding Older Browsers</a>
</li>
</ul>
                    </div>
                </div>
            

            
                <div class="sidebox">
                    <div class="hd">
                        <h2 class="no-toc">Examples</h2>
                    </div>

                    <div class="bd">
                        <ul class="examples">
                            
                                
                                    <li data-description="Shows how to instantiate multiple Panel instances, and use nested modality to interact with a Datatable.">
                                        <a href="panel-form.html">Creating a modal form</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Shows how to create a panel that animates as it is shown and hidden">
                                        <a href="panel-animate.html">Creating an animated panel</a>
                                    </li>
                                
                            
                        </ul>
                    </div>
                </div>
            

            
        </div>
    </div>
</div>

<script src="../assets/vendor/prettify/prettify-min.js"></script>
<script>prettyPrint();</script>

</body>
</html>
